\chapter{Tutorial \label{tutorial}}

Once you have installed Aspen, here are some quick walk-throughs to get your
feet wet. They are written sequentially.


\section{"Greetings, program!" \label{tutorial-greetings-program}}

In your home directory, make a new directory named \file{aspentut}. Create a
file in \file{aspentut} named \file{index.html}, with the following contents:

\begin{verbatim}
Greetings, program!
\end{verbatim}

At the command line in the \file{aspentut} directory, type \code{aspen}. You
should get output like this:

\begin{verbatim}
$ aspen
aspen starting on ('', 8080)
\end{verbatim}

Now open a web browser and hit \code{http://localhost:8080/}. You should see
"Greetings, program!" in your browser. Congratulations!


\section{Your First Handler \label{tutorial-handler}}

Aspen uses \dfn{handlers} to process files such as your \file{index.html}. Now
we are going to write our own handler.

First, create a directory under \file{aspentut} named \file{__} (that's two
underscores). This is \file{aspentut}'s \dfn{magic directory}, and it is where
you configure and extend your website. Now create two directories under the
magic directory: \file{etc} and \file{lib}. Under \file{lib}, create a
\file{python2.x} directory, where \file{x} corresponds to the minor version of
Python you are using. Your directory structure should now look like this:

\begin{verbatim}
aspentut
aspentut/__
aspentut/__/etc
aspentut/__/lib/python2.x
\end{verbatim}

In \file{__/lib/python2.x}, create a file named \file{handy.py} with the
following contents:

\begin{verbatim}
def handle(environ, start_response):
    start_response('200 OK', [('Content-Type', 'text/plain')])
    return [environ['PATH_TRANSLATED']]
\end{verbatim}

And in \file{__/etc}, create a file named \file{handlers.conf} with these
contents:

\begin{verbatim}
fnmatch aspen.rules:fnmatch

[handy:handle]
fnmatch *.asp
\end{verbatim}

What we have done is we have defined a new handler, and wired it up to be used
for any request for a file with the extension \file{.asp}. So now let's create
such a file at \file{aspentut/handled.asp} and give it the following contents:

\begin{verbatim}
Greetings, program?
\end{verbatim}

Restart Aspen, then hit \code{http://localhost:8080/handled.asp}. You should see
the filesystem pathname of the file being served.

If you are familiar with the WSGI specification, you will recognize that
\function{handy.handle} is a WSGI callable. Aspen plugins all speak WSGI. Also
notice that the rules for when a certain handler is invoked are themselves
extensible. The \code{fnmatch} rule comes with Aspen, but you can also write
your own.


\section{What You've Learned \label{tutorial-learned}}

In this brief tutorial we've introduced these key facts about Aspen:

\begin{itemize}
\item{Aspen websites use the filesystem for site hierarchy.}
\item{Aspen websites are configured and extended via a "magic directory."}
\item{Aspen configuration happens through plain-text configuration files.}
\item{Aspen extensions are WSGI callables.}
\end{itemize}

Besides handlers, Aspen can be extended by wiring up arbitrary WSGI apps to
certain paths, and maintaining a global WSGI middleware stack. If this all fits
your style of development, then check out the reference documentation that
follows for the full story.
